---
title: "Pivot Column Groups"
enterprise: true
---
The grid generates pivot column groups representing each unique pivoted value.

{% gridExampleRunner title="Column Group Summary Example" name="column-group-summary"  /%}

## Customising Group Definitions

Pivot Result Column Group definitions can be configured using the `processPivotResultColGroupDef` grid option.

{% apiDocumentation source="grid-options/properties.json" section="rowPivoting" names=["processPivotResultColGroupDef"] /%}

In the example below, the `processPivotResultColGroupDef` callback is used to apply a class to the group header cells,
which is subsequently used to style them with a golden background.

{% gridExampleRunner title="Column Group Definitions Example" name="column-group-definitions-example"  /%}

This demonstrates the following configuration for applying a class to the group header cells:
```{% frameworkTransform=true %}
const gridOptions = {
    pivotMode: true,
    processPivotResultColGroupDef: (colDef) => {
        colDef.headerClass = 'pivot-gold'; // the params are mutated directly, not returned
    },
}
```

## Ordering Groups

The pivot result groups are initially displayed in alphabetical order. You can change this default order by providing a `pivotComparator`
function to the pivoted column's definition.

{% apiDocumentation source="column-properties/properties.json" section="pivoting" names=["pivotComparator"] /%}

In the example below, note that a `pivotComparator` has been supplied to the `sport` column, and the pivot result groups are instead
sorted in reversed alphabetical order.

{% gridExampleRunner title="Ordering Pivot Groups" name="order-pivot-groups" /%}

This demonstrates the following configuration for modifying the resulting order of groups:
```{% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        // ...other column definitions
        {
            field: 'sport',
            pivot: true,
            pivotComparator: (a, b) => b.localeCompare(a),
        },
    ],
    pivotMode: true,
}
```

{% note %}
If the `pivotComparator` returns 0, the order of the groups is then further determined by the order in which they appear in the data.

This means that writing a `pivotComparator` function that always returns 0 will result in the groups being ordered by the order in which they appear in the data.
{% /note %}

### Changing Data, Filters, and Configurations

When changing data, filters, or configurations such as `pivotRowTotals` the generated column groups and their order is impacted. The grid will add
new columns and column groups at the end of their parent groups. This is to maintain any changes the user may have made to their column order.

This behaviour can be toggled to instead reset the column order when the columns are generated by setting the `enableStrictPivotColumnOrder` grid option to `true`.

The example below demonstrates a changing data set while in pivot mode. Note that when `enableStrictPivotColumnOrder` is set to `false`, 
new columns are appended. When set to `true` all columns are re-sorted according to the `pivotComparator` (or alphanumerically if omitted).
{% gridExampleRunner title="Strict Column Order" name="strict-column-order" exampleHeight=200 /%}

This demonstrates the following configuration for changing the behaviour for new column groups:
```{% frameworkTransform=true %}
const gridOptions = {
    enableStrictPivotColumnOrder: true,
}
```

## Pivoting by Dates and Times

When pivoting by date/time values, the grid can optionally generate pivot group columns based on components of the date/time.

To enable this for a particular column, use the `groupHierarchy` property of the [Column Definition](./column-properties/#reference-grouping-groupHierarchy).

{% apiDocumentation source="column-properties/properties.json" section="grouping" names=["groupHierarchy"] /%}

```{% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        {
            field: 'date',
            pivot: true,
            groupHierarchy: ['year', 'month']
        },
        // ...other column definitions
    ],
};
```

This snippet is illustrated in the example below.

{% gridExampleRunner title="Pivoting by Dates and Times" name="pivoting-date-time" /%}

{% note %}
Date values must be formatted as ISO-8601 dates in order to be correctly parsed into their components.
{% /note %}

## Filtering Pivoted Columns

When pivoting is active, filters can be applied to columns defined within the column definitions by using
the [Filters Tool Panel](./tool-panel-filters/) and the [Filter API](./grid-api/#reference-filter).

In the example below, applying a filter to the `Sport` column (which has been pivoted) impacts the generated pivot column groups,
instead of the grid rows or cell values.

{% gridExampleRunner title="Filtering Pivoted Columns" name="filter-pivoted-columns" /%}

{% note %}
When filtering a pivoted column, the resulting pivot result column group is removed from the grid. If the filter is subsequently removed, the column group will be re-added to the end of grid.

To configure this behaviour, refer to the section for [Changing Data, Filters, and Configurations](./pivoting-column-groups/#changing-data-filters-and-configurations).
{% /note %}

## Expanded by Default

Pivot Column Groups can be configured to expand by default, down to a given depth. This depth can be configured using the `pivotDefaultExpanded` grid option.

The example below demonstrates `pivotDefaultExpanded` being used to expand the first pivot group level by default. Providing `-1` will expand all pivot group levels by default.

{% gridExampleRunner title="Open Pivot Group By Default" name="open-pivot-group-by-default" /%}

The example above demonstrates the following configuration for expanding pivot groups by default:
```{% frameworkTransform=true %}
const gridOptions = {
    pivotDefaultExpanded: 1,
}
```

## Prevent Expanding Groups

When using multiple pivot columns, groups become expandable by default. To prevent this and instead always show all columns, set the grid option `suppressExpandablePivotGroups=true`.

{% gridExampleRunner title="Fixed Pivot Column Groups" name="fixed-pivot-column-groups" /%}

The example above demonstrates the following configuration:
```{% frameworkTransform=true %}
const gridOptions = {
    pivotMode: true,
    suppressExpandablePivotGroups: true,
}
```

## Hide Group with Single Value Column

When pivoting with only one aggregated column, you can simplify the grid column header layout by omitting pivot column groups
with only one child column.
Enabling the grid option `removePivotHeaderRowWhenSingleValueColumn=true`, when set to `true` will instead skip the group and
use the pivot keys to label the pivot result column instead.

{% gridExampleRunner title="Hiding Repeated Column Labels" name="hidden-single-value-column-header" /%}

The example above demonstrates the following configuration:
```{% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        { field: 'country', rowGroup: true },
        { field: 'sport', pivot: true },
        { field: 'gold', aggFunc: 'sum' },
    ],
    pivotMode: true,
    removePivotHeaderRowWhenSingleValueColumn: true,
};
```

## Next Up

Display the total aggregation of rows and columns when pivoting with [Pivot Totals](./pivoting-totals/).
